Add some content to the migration guide

Start a new migration guide

Remove information that is only relevant for porting to GTK+ 3,
and put scaffolding in place for information relevant to GTK+ 4.

gsk: Clear the profiler instance

When disposing the GskRenderer.

gsk: Plug leak in GskRenderNode

We need to destroy the node's surface when finalizing it.

build: Fix variable name for gtk4-update-icon-cache target

build: Rework the GSK source lising

We need to only parse the public sources during the introspection step,
otherwise the introspection scanner will try to access private data
types.

build: Drop LDADD from GSK's Makefile

We can use the LDFLAGS target build.

Rename all binaries to be versioned

This is just easier to avoid parallel installation problems.

Rename gtk-query-immodules to follow our binary naming scheme

Instead of gtk-query-immodules-4.0, lets call it gtk4-query-immodules,
to use the same prefix as all the other versioned binaries.

Fix the docs build more

This makes gtk-doc produce output again.

gdk: Fix Since tag of gdk_cairo_surface_upload_to_gl

gdk: Add missing Since tags for gdk_window_new_child/input

In addition to d22e5e69d93401f8f0a040767fbf69ac5643a19d

gsk: Bump up all version annotations

GSK is part of the 4.0 development cycle.

docs: Bump up major version for GSK's API reference

gsk: Add the ability to create fallback renderers

While porting GTK to GskRenderer we noticed that the current fallback
code for widgets using Cairo to draw is not enough to cover all the
possible cases.

For instance, if a container widget still uses GtkWidget::draw to render
its children, and at least one of them has been ported to using render
nodes instead, the container won't know how to draw it.

For this reason we want to provide to layers above GSK the ability to
create a "fallback" renderer instance, created using a "parent"
GskRenderer instance, but using a Cairo context as the rendering target
instead of a GdkDrawingContext.

GTK will use this inside the gtk_widget_draw() implementation, if a
widget implements GtkWidgetClass.get_render_node().

gsk: Update Cairo renderer

The Cairo renderer has been lagging behind a series of changes inside
GskRenderer, like surface-less nodes, so it needs to be updated.

gsk: Make GskRenderer.render() drawing context-agnostic

We're going to need to allow rendering on a specific cairo_t in order to
implement fallback code paths inside GTK; this means that there will be
times when we have a transient GskRenderer instance that does not have a
GdkDrawingContext to draw on.

Instead of adding a new render() implementation for those cases and then
decide which one to use, we can remove the drawing context argument from
the virtual function itself, and allow using a NULL GdkDrawingContext
when calling gsk_renderer_render(). A later commit will add a generic
function to create a transient GskRenderer with a cairo_t attached to
it.

Renderers inside GSK will have to check whether we have access to a
GdkDrawingContext, in which case we're going to use it; or if we have
access to a cairo_t and a window.

docs: Update the GSK API reference section

gsk: Move GskRenderNode getters to internal API

GskRenderNode is, at its core, a write-only API; you're supposed to set
up the render nodes instead of querying them for state.

Querying render nodes is left to the GskRenderer implementation.

gsk: Remove GskRenderer:auto-clear

We control the clearing inside each GskRenderer implementation, and we
don't allow providing a target surface any more.

Convert GtkSpinner to indirect rendering

Convert GtkImage to indirect rendering

Convert GtkAccelLabel to indirect rendering

Convert GtkLabel to indirect rendering

Warning! This breaks GtkAccelLabel. It will be fixed in the next
commit.

Convert GtkFlowBox to indirect rendering

container: Prepare to prune render nodes

Add a should_propagate function for render nodes. Eventually,
this is meant to avoid creating render nodes for child widgets
that are outside the parents clip area. Since we don't have
that information available right now, just filter out nondrawable
children for now.

Split css background into individual render nodes

Use separate render nodes for each layer in a multi-image
background. WARNING: blend modes don't work right yet.

Add blend mode to debug spew

Don't create render nodes for empty backgrounds

Break out the css background render node in a function

This is in preparation for creating separate render nodes
for individual backgrounds.

Make outer shadows work again

Change get_render_node to return nodes that are sized to the clip
area and expect to be placed at the clip position; change
gtk_container_propagate_render_node to place child render nodes
accordingly, and change gtk_css_gadget_get_render_node to return
nodes that are sized accordingly as well.

gsk: Fix hidpi scaling

We store the vertices in (unscaled) window coords (but the item size
is still scaled to match the texture size). Also, the
projection/model-view multiplication order is switched so that the scale
is applied at the right place.

gdk_cairo_surface_upload_to_gl: Don't apply device scale

The arguments to this function is the texture width/height, and these
are already scaled.

gsk: Remove :use-alpha from GskRenderer

It's unused, and we always assume we render with an alpha channel
enabled because it's 2016.

gsk: Move scaling filters to GskRenderNode

The renderer will always use nearest-neighbor filters because it renders
at 1:1 pixel to texel ratio.

On the other hand, render nodes may be scaled, so we need to offer a way
to control the minification and magnification filters.

gsk: Allow adding a GL texture as a node content

If we already have a GL texture we definitely don't want to use
gdk_cairo_draw_from_gl() to draw on a Cairo context if we're going
to take the Cairo surface to which we draw and put it into an OpenGL
texture.

gsk: Drop modelview/projection from GskRenderer API

The details of the modelview and projection matrices are only useful for
the GL renderer; there's really no point in having those details
available in the generic API — especially as the Cairo fallback renderer
cannot really set up a complex modelview or a projection matrix.

gtk: Sort children by window depth when rendering

This makes popovers pop over instead of under.

gsk: Ensure that non-drawing nodes are supported

Non-drawing nodes should skip the texturing phase.

gtk: Add a box render node for gadgets

Instead of using the background as the gadget's node, we add a
non-drawing node that can be used to apply offsets; all other nodes are
children of the "box" node.

gsk: Fix the blend mode

The default blend mode should be the equivalent of Cairo's OVER
operator.

gsk: Reuse VAOs with identical buffers

Just like we reuse texture ids with the same size we can, at the expense
of a little memory, reuse vertex buffers if they reference the same
attributes and contain the same data.

Each VAO is marked as free at the end of the frame, and if it's not
reused in the following frame, it gets dropped.

gsk: Remove child-transform from render nodes

The child-transform is useful only if we also provide clipping to the
parent nodes, otherwise children will just be drawn outside of the
parent's bounds.

We'll introduce child transforms either at a higher layer, or once we
add clipping support to GskRenderNode.

Covert GtkOverlay to indirect rendering

There is no gadget, so we use the gtk_widget_create_render_node
function for the first time here.

Convert GtkComboBox to indirect rendering

The removal of the draw method in GtkComboBox reveals another
instance of parent-child invariant violation in GtkComboBoxText.

GtkButtonBox: Convert to indirect rendering

Small documentation additions

Small fixes for the docs

Set titles and short descriptions for the sections.

gsk: Build docs

GtkListBox: Convert to indirect rendering

Note that there is a problem with the pixel cache that causes
listboxes to come out black when in a scrolled window.

gadget: Fix handling of custom content

The transformations here were wrong, causing content to go nowhere.
This patch fixes check and radio buttons to appear as expected.

GtkCheckButton: Convert to indirect rendering

This is another example of indirect rendering with a box gadget.
There is currently still some positioning problem with the
checkmark.

Prevent box gadget content from being drawn twice

Now that we split out box gadget children into separate
render nodes, we must not draw them onto the box gadgets
node anymore.

GtkExpander: Convert to indirect rendering

This is the first example of indirect rendering involving
a box gadget. For now, we iterate the child gadgets manually,
and rely on gtk_container_propagate_render_node for the
child widgets. Eventually, we may want a better solution
here.

gadget: Add a has_content vfunc

...and implement it for GtkCssGadget and GtkCssCustomGadget.
This allows us to decide on a per-object basis if a custom
gadget needs a render node for content or not.

button: Restore focus

The custom gadget draw function has the side effect of informing
the gadget machinery wether to draw focus or not. Bring the
draw function back, just for its boolean return value. We may
want to find a better solution for this.

Allow selective debug spew

I don't think this should stay in the code long-term, but it
is useful for debugging. It helped me track down some suspicious
placements of render nodes.

Add details to css render nodes

Give all nodes the same detail about the owner widget.
This reveals that every GtkCssCustomGadget gets a
DrawGadgetContents node, even if their draw_func is NULL.
We may want to come up with a better solution for that.

Some debug help

Make the bounds of drawing surfaces created by render nodes visible.

Trigger with GSK_DEBUG=surface.

Drop an unused variable

gtk: Clean up render fallback node creation in GtkWidget

gtk: Port GtkHeaderBar to render nodes

gtk: Port GtkActionBar to render nodes

gtk: Attempt at handling CSS coordinates

When creating the GskRenderNodes for the gadgets we should not translate
the coordinates inside the Cairo context, but we should tweak the
coordinates of the anchor point.

This is still not enough to get an appropriate rendering, as the result
is still slightly offset to the left.

gsk: Pass the appropriate value for the n_quads argument

Instead of passing the size of the buffer, we should pass the number of
quads; we know what the size of a single quad structure is, so we can do
the multiplication internally when creating the VAO.

This allows us to print the quads for debugging purposes.

GtkFrame: Convert to indirect rendering

Create a GskRenderNode for the contents of the frame.

gtk: Add convenience function for creating render nodes

GtkWidget.create_render_node() sets up a GskRenderNode appropriate for
rendering the contents of a widget, including its bounds,
transformation, and anchor point.

gsk: Rename set_offset() to set_anchor_point()

The naming is consistent with other scene graph libraries, as it
represents an additional translation transformation applied on top of
the provided transformation matrices.

We can also simplify the implementation by applying the translation when
we compute the world matrix.

gsk: Recycle textures across frames

We keep the textures used inside a frame around until the end of the
following frame; whenever we need a texture with the same size, and
it's not marked in use, then we just reuse the existing texture.

Fix fallback render nodes

We were allocating a surface thats big enough for the clip, and
we were setting the transform for that, but then GtkContainer
was overriding the transform with the one for the allocation.
Also, we were drawing at the clip position, not the allocation
position.

Add an offset to render nodes

This will let us account for the difference between
clip and allocation.

gsk: Split of debug spew for transforms

This was overwhelming other useful debug output, so make it
opt-in. We print the render items for both opengl and transforms,
since the matrices bleed into each other, otherwise.

gsk: Add debug macros that trigger on two conditions

This will be useful in the following commits.

gsk: Add a debug flag for transforms

gsk: Improve debug output a bit

Indent render node debug spew to make the tree structure obvious.

button: Convert to indirect rendering

WARNING! This commit breaks GtkButton subclasses.

Convert GtkGrid to indirect rendering

Following the example of GtkBox.

gsk: Add GskProfiler to GskRenderer

The profiler instance is per-renderer, and is accesible to
implementations.

gsk: Add profiler object

The GskProfiler holds counters and timers, and will be used by the
renderer implementations to acquire frame timings.

box: Port from immediate to deferred rendering

Drop the ::draw() vfunc implementation in favour of the
::get_render_node() vfunc.

Integrate CSS gadget with GSK render nodes

First stab at an internal API that generates render nodes when drawing a
CSS gadget.

gtk: Update the coordinates when propagating render nodes

Just like gtk_container_propagate_draw() does for the immediate mode
rendering.

Use the projection to flip around the content

Since we use an FBO to render the contents of the render node tree, the
coordinate space is going to be flipped in GL. We can undo the flip by
using an appropriate projection matrix, instead of changing the sampling
coordinates in the shaders and updating all our coordinates at render
time.

widget: Fix compatibility fallbacks

gsk: Add texture size to debug message

gsk: Take into account the scaling factor

We need to apply a scaling factor whenever we deal with user-supplied
coordinates, like:

 - when creating textures
 - when setting up the viewport
 - when submitting the scene

gsk: Tie render nodes to renderers

Render nodes need access to rendering information like scaling factors.
If we keep render nodes separate from renderers until we submit a nodes
tree for rendering we're going to have to duplicate all that information
in a way that makes the API more complicated and fuzzier on its
semantics.

By having GskRenderer create GskRenderNode instances we can tie nodes
and renderers together; since higher layers will also have access to
the renderer instance, this does not add any burden to callers.

Additionally, if memory measurements indicate that we are spending too
much time in the allocation of new render nodes, we can now easily
implement a free-list or a renderer-specific allocator without breaking
the API.

gsk: Bind GL context to the GL profiler

Similarly to how we bind it to the GL driver object used by the GSK GL
renderer.

gtk: Port GtkWindow to render nodes

WARNING: BROKEN COMMIT

gtk: Add GtkContainer API to gather render nodes

We cannot implement GtkWidgetClass.get_render_node() in GtkContainer
without breaking the fallback path that renders a widget to a single
render node rasterization. For GtkContainer subclasses we should provide
a simple API, similar to gtk_container_propagate_draw(), that gathers
all the render nodes for each child.

gtk: Name GSK render nodes

For debugging purposes it's helpful to name the nodes.

gsk: Fix build without Wayland

gsk: Add redirection to FBOs for opacity groups

If a node is non-opaque and has a non-zero opacity we need to paint its
contents and children first to an off screen buffer, and then render the
resulting texture at the desired opacity — otherwise the opacities will
combine and result in the wrong rendering.

gsk: Drop opaque/transparent item split

We're not going to use separate rendering lists soon, and the way we
render items is less similar to a gaming engine and more similar to a
simpler compositor. This means we don't need to perform a two pass
rendering — opaque items first, transparent items later.

gsk: Rename uniforms and attributes in shaders

Use appropriate names, and annotate the names with the types — 'u' for
uniforms, 'a' for attributes. The common preambles for shaders are split
from the bodies, so we need some way to distinguish the uniforms and the
attributes just from their name.

gsk: Move resource handling inside GskGLDriver

We want the GL driver to cache as many resources as possible, so we can
always ensure that we're in a consistent state, and we can handle state
transitions more appropriately.

gsk: Simplify buffer handling in GskGLRenderer

We don't have optional stencil and depth buffers, like GtkGLArea: we
always create both of them internally.

gsk: Drop render buffer code path from GskGLRenderer

We always use texturing, to preserve the alpha channel when blitting the
frame buffer object on the window surface.

gsk: Rework surface -> texture API

Drop the texture parameters handling from the texture creation, and
associate them with the contents upload. Also, rename the function to
something more in line with what it does.

gsk: Add GL driver API to create render targets

It's going to be used by the GL renderer to safely create and bind
FBOs when needed.